HiliteText

HiliteText
Header:	QuickdrawText.h		Carbon status:	Supported

Finds all the characters between two byte offsets in a text segment whose glyphs are to be highlighted.

void HiliteText (
    Ptr textPtr, 
    SInt16 textLength, 
    SInt16 firstOffset, 
    SInt16 secondOffset, 
    OffsetTable offsets
);

Parameter descriptions

textPtr: A pointer to a buffer that contains the text to be highlighted.
textLength: The length in bytes of the entire text segment pointed to by textPtr.
firstOffset: The byte offset from textPtr to the first character to be highlighted.
secondOffset: The byte offset from textPtr to the last character to be highlighted.
offsets: A table that, upon completion of the call, specifies the boundaries of the text to be highlighted.

DISCUSSION

The HiliteText function returns three pairs of byte offsets that mark the onscreen ranges of text to be highlighted. This is because for bidirectional text, although the characters are contiguous in memory, their displayed glyphs can include up to three separate ranges of text.

The HiliteText function takes into account the fact that to highlight the complete range of text whose beginning and ending byte offsets you pass it, it must return byte offsets that encompass the glyphs of the first and last characters in the text segment. To determine the correct offset pairs, HiliteText relies on the primary line direction as specified by the SysDirection global variable.

Before calling HiliteText, you must set up an offset table (of type OffsetTable) in your application to hold the results. You can consider the offset table to be a set of three offset pairs.

If the two offsets in any pair are equal, the pair is empty and you can ignore it. Otherwise the pair identifies a run of characters whose glyphs are to be highlighted.

The offsets that HiliteText returns depend on the primary line direction as defined by the SysDirection global variable. If you change the value of SysDirection, HiliteText returns the offset that is meaningful according to the primary line direction for ambiguous offsets on the boundary of right-to-left and left-to-right text.

SPECIAL CONSIDERATIONS

The HiliteText function may move memory; do not call this function at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.